Update release notes for the Markdown era #213
Conversation
colleenmcginnis
changed the title
There was a problem hiding this comment.
I'm not very familiar with the codebase, so my comments are fairly high-level.
Can we make impact and action required for breaking-change, deprecation, or known-issue fragments?
I understand breaking-change and deprecation usage.
Can you provide an example of known-issue? I'm probably just missing some context of how to use.
I'm not very familiar with where the best to spot to "enforce" this change. I think if we wanted to require impact and action, it would be in build (this is how we validate in PR checks).
Should we continue to accept template instead of file_type?
I don't have context about the usage of --template to answer. In my limited experience, I've never used that flag.
|
Thanks @ebeahan!
Is there anyone else who should review?
I initially included automation for adding content to the Markdown known issues page, but I ended up removing it since recently we've been adding known issues manually post-release (example, example, example, example). I'm not sure if we should try to automate those.
Prior to this PR, there was only one template available, |
Let me reach out to my team and ask for some additional feedback. |
|
Even if you are no more handling this project, maybe you can still take a look here @endorama? |
|
From what I know, we are not automatically checking the fragment content but only if a fragment is available in the PR. |
There was a problem hiding this comment.
LGTM.
@colleenmcginnis do create a new release once these changes are merged.
…elease notes (#2818) Related to elastic/docs-projects#488 elastic/elastic-agent-changelog-tool#213, elastic/elastic-agent#9440, elastic/fleet-server#5374⚠️ **DO NOT MERGE BEFORE elastic/docs-builder#1830 IS BOTH MERGED AND INCLUDED IN A NEW RELEASE**⚠️ Removes the combined Fleet Server and Elastic Agent release notes in favor of separate release notes in the fleet-server and elastic-agent repos. This enables the dev team to own the release notes process.
4 participants
🧀 Pairs with elastic/elastic-agent#9440
Overview
Adds the ability to generate Markdown files for release notes, breaking changes, and deprecations in the new format used on https://www.elastic.co/docs/release-notes/fleet.
Approach
Updates the
rendercommand to accept--file_typeset to eitherasciidocormarkdown.asciidoc, it renders a single AsciiDoc file containing release notes for a given version using the existingasciidoc-embeddedtemplate.markdown, it renders three Markdown files for a given version:markdown-index-templatetemplate and the resulting file is<version>/index.md.markdown-breaking-templatetemplate and the resulting file is<version>/breaking.md.markdown-deprecations-templatetemplate and the resulting file is<version>/deprecations.md.Adds two new fields to the fragment template to be used when the
kindisbreaking-change,deprecation, orknown-issue:impact: User impact of the change (a few sentences).action: Steps for mitigating the described user impact (a few sentences).Updates the recommended configuration file name (from
configtoconfig.changelog.yaml) and format for individual repos (elastic-agent and fleet-server) in order to save the rendered files in the appropriate location so all versions can be compiled onto a page for each: release notes, breaking changes, and deprecations. See an example of this structure in elastic/elastic-agent#9440.Open questions
impactandactionrequired forbreaking-change,deprecation,orfragments?known-issuetemplateinstead offile_type?